home *** CD-ROM | disk | FTP | other *** search
/ Monster Media 1996 #15 / Monster Media Number 15 (Monster Media)(July 1996).ISO / internet / htmst604.zip / HTMSTRIP.DOC < prev    next >
Text File  |  1996-04-13  |  18KB  |  351 lines
  1. HTMSTRIP.DOC                         1                         Revised: 04/13/96
  2.  
  3. The HTMSTRIP.EXE program attempts to read HTML pages, remove  the  HTML  coding,
  4. and write the file out as something more useful.  Features of this program:
  5.  
  6.   * Can be run across an entire subdirectory (for example, your entire
  7.     cache subdirectory), and will only process the HTML documents that it finds.
  8.     (There are some options on this.)
  9.   * Removes all imbedded HTML commands.
  10.   * Recodes the standard HTML "entity references" (e.g. "©" becomes
  11.     "(c)").  The actual replacements are coded in a user-modifiable lookup file.
  12.   * Handles standard indent, heading, selection groups, menus, tables, etc.
  13.   * Reflows all text as appropriate
  14.   * Optionally, will replace Link, Image, and Input references with
  15.     user-definable text representations.
  16.   * Optionally, alerts you to possible errors in the HTML code itself.
  17.  
  18. HTML codes are surrounded within <...>  indicators.   For  upward  compatibility
  19. reasons, Web browsers ignore any codes  that  they  don't  understand  and  just
  20. process the ones they can handle.
  21.  
  22. Note that the HTMSTRIP command is currently geared for handling HTML  2.0  files
  23. and then Netscape table-specific extensions (added to HTML 3.0).
  24.  
  25. HTMSTRIP removes all HTML codes.  It also  handles  the  standard  HTML  "&xxx;"
  26. "entity references" (e.g. "©" is replaced by "(c)").  You can add or change
  27. these replacements as desired by using the INI file (documented later).
  28.  
  29. HTMSTRIP is also tuned to allow it to  specially-handle  several  embedded  HTML
  30. codes.  These codes are the following:
  31.  
  32.        <A ...>                       External link
  33.        <BLOCKQUOTE>...</BLOCKQUOTE>  Indented block of text
  34.        <BR>                          Forced line break
  35.        <CAPTION>...</CAPTION>        Title for a table
  36.        <CENTER>...</CENTER>          Centering text
  37.        <DD>                          Term definition
  38.        <DIR>...</DIR>                Directory list of items
  39.        </DL>                         End of definition list
  40.        <DT>                          First term of definition list/glossary
  41.        <H1> to <H6>...</H1> to </H6> Heading items
  42.        <HR>                          Horizontal rule
  43.        <IMG ...>                     Image
  44.        <INPUT ...>                   User input
  45.        <LI>                          Menu/Ordered/Unordered/Directory list item
  46.        <MENU>...</MENU>              Menu listing
  47.        <OL>...</OL>                  Ordered listing
  48.        <OPTION>                      Used for single/multiple choice menus
  49.        <P>                           Paragraph indicator
  50.        <PRE>...</PRE>                Preserve spacing block (preformatted text)
  51.        <SELECT>...</SELECT>          Block for single/multiple choice menu
  52.        <TABLE>...</TABLE>            Table block
  53.        <TD>...</TD>                  Table data (cell)
  54.        <TH>...</TH>                  Table heading
  55.        <TITLE>...</TITLE>            Title item
  56.        <TR>...</TR>                  Table row
  57.        <UL>...</UL>                  Unordered listing
  58.  
  59.  
  60. HTMSTRIP.DOC                         2                         Revised: 04/13/96
  61.  
  62. If you run across other codes that become vital, let me know  and  I'll  try  to
  63. handle them somehow.
  64.  
  65.  
  66. How to get HTML files:
  67.  
  68. Some people who are using regular Web browsers like  Mosaic  or  Netscape  don't
  69. realize that  they're  automatically  saving  HTML  files  to  their  hard  disk
  70. throughout every Web session.  That's because just about every Web browser saves
  71. the most-recently accessed files from  the  Web  (including  HTML  source  code,
  72. GIF's, and JPG's) on your hard  disk  and  reads  them  from  there  instead  of
  73. requiring you to download them every time you go back to a previous page.   This
  74. is typically settable by  you  under  "Preferences"  and  "Cache"  on  your  Web
  75. browser.
  76.  
  77. I usually set my Web browser to have a huge cache, maybe 10MB.   Anything  beats
  78. downloading the same pages over again even at 28.8K.  And I make sure that I  do
  79. not have anything specified like "clear cache at the end of every session". Then
  80. I just go through the files in the cache subdirectory  afterward  and  reprocess
  81. them.
  82.  
  83. Two disadvantages to a cache...  It takes up hard disk space but, hey,  the  Web
  84. browser  is  typically  in  Windows  so  why  are  you  surprised.   The  second
  85. disadvantage is  that  if  the  page  actually  changes  between  sessions,  you
  86. typically won't notice the new page as long as it remains in your cache.  If you
  87. think a page is still in cache and should have been changed but didn't, you  can
  88. typically ask your Web browser to reload the page.  On some  browsers,  this  is
  89. shown as an arrow in the form of a circle.
  90.  
  91. HTMSTRIP can process the entire cache subdirectory.   It  automatically  detects
  92. non-HTML files for you and processes accordingly.   It  creates  new  text  file
  93. versions of just the HTML pages it finds.
  94.  
  95. By the way, for some reason, the current  beta  version  of  Netscape  typically
  96. ignores my cache setting for some reason.  I don't have the slightest idea  why.
  97. As a result, when you Alt-F4 out of Netscape, it goes through  and  deletes  all
  98. but a few of the temporary files.  This is annoying to  say  the  least.   As  a
  99. result, I have to run HTMSTRIP from a DOS window just before  leaving  Netscape.
  100. If anyone knows why it does this to me, please let me know!
  101.  
  102.  
  103. Specifying parameters:
  104.  
  105. Parameters for this program can be set in the following ways.  The last  setting
  106. encountered always wins:
  107.   - Read from an *.INI file (see BRUCEINI.DOC file),
  108.   - Through the use of an environmental variable (SET HTMSTRIP=whatever), or
  109.   - From the command line (see "Syntax" below)
  110.  
  111.  
  112.  
  113. HTMSTRIP.DOC                         3                         Revised: 04/13/96
  114.  
  115. Defining entity references:
  116.  
  117. HTMSTRIP will process an entity reference definition file is one is found.  This
  118. table can be in your standard *.INI file (e.g. HTMSTRIP.INI) if  desired  or  it
  119. can be a separate file specified using the /Linitfile parameter.
  120.  
  121. Entity references are how non-standard characters like the  copyright  character
  122. are handled in HTML pages.  Entity references are  indicated  as  "&xxx;"  where
  123. "xxx" is either a code or a number preceded by  a  pound  sign.   The  copyright
  124. symbol is indicated in HTML as "©".
  125.  
  126. A default HTMSTRIP.INI is provided with over 230 entity reference  lookups.   To
  127. define or change these lookups, the INI file should include a series of lines in
  128. the following format:
  129.  
  130.         &xxx; = outstr
  131.  
  132. where "&xxx;" is the HTML sequence and "outstr" is what you want to  replace  it
  133. with.  The  "outstr"  portion  can  consist  of  regular  non-space  ASCII  text
  134. characters (like "A" or "z") as well as hexadecimal values (in the form &Hxx) or
  135. decimal values (in the form \nnn).  (See the BRUCEHEX.DOC file.) It can also  be
  136. the word "NULL" which translates the string into  nothing.   You  cannot  use  a
  137. space or equal sign in "outstr"; use the hexadecimal or decimal  representations
  138. instead.  The table does not have to be in any specified order.  Lines  can  end
  139. with "/*" followed by a comment if you want.  Examples:
  140.  
  141.         ©   = (c)      /* Copyright symbol
  142.         °    = °
  143.         é = é
  144.         ê  = ê
  145.         è = è
  146.             = \032
  147.  
  148. Remember  that  "&xxx;"  entity  references  (yes,  I  hate  that  phrase)   are
  149. case-sensitive in HTML.  "°" will not find "&Deg;".
  150.  
  151. There seems to be a trend of late  to  relax  some  of  the  replacement  coding
  152. requirements in Web pages.  The  ";"  is  now,  apparently,  becoming  optional.
  153. Numeric replacements (e.g. " ") seem to no longer require the leading  pound
  154. sign.   Therefore,  HTMSTRIP  looks  for  both  of  these  iterations  for   any
  155. appropriate lookup.  "©" will find "©" and "™" will  find  "&153".
  156. The lookup itself has to be entered in the formally correct way though.
  157.  
  158. You are also allowed to redefine the strings that are used  for  three  symbolic
  159. references in the file.  These show  up  only  if  /SYMBOLS  is  specified.   By
  160. default, you will see the following:
  161.  
  162.         for <A> external links             -> (link)
  163.         for <IMG> image references         -> (image)
  164.         for <INPUT> user inputs            -> [Input]
  165.  
  166.  
  167. HTMSTRIP.DOC                         4                         Revised: 04/13/96
  168.  
  169. You can redefine any and all of these entity references in the same lookup file.
  170. These substitutions are specified more or less like the previous substitutions:
  171.  
  172.         <A>      = (link)
  173.         <IMG>    = (image)
  174.         <INPUT>  = [Input]
  175.  
  176. Unlike with  the  other  lookups,  the  left  side  is  not  case  sensitive  so
  177. "<a>=(link)" works just fine.  Hexadecimal and decimal  replacements  are  again
  178. acceptable (see BRUCEHEX.DOC file).  You might, for example,  want  to  redefine
  179. some of them like this:
  180.  
  181.         <A>      = \251     /* Replaces with a √ symbol
  182.         <IMG>    = \015     /* Replaces with a  symbol (little flash cube)
  183.         <INPUT>  = ?        /* Replaces with a question mark
  184.  
  185. Any symbolic references that you do not redefine will default to their  original
  186. values.  If /-SYMBOLS is specified, any symbolic definitions are ignored  and  a
  187. "NULL" replacement string is used for all of them.
  188.  
  189.  
  190.  
  191. HTMSTRIP.DOC                         5                         Revised: 04/13/96
  192.  
  193. Syntax:
  194.  
  195.     HTMSTRIP { filespec | @listfile } [ outfile ] [ /EXT=.xxx ]
  196.       [ /WIDTH=n ] [ /SYMBOLS | /-SYMBOLS ] [ /ALL ] [ /SITE | /FSITE | /-SITE ]
  197.       [ /ALT ] [ /SPACES | /-SPACES ] [ /WARNINGS | /-WARNINGS ]
  198.       [ /RULE=s ] [ /BORDER=c ] [ /BUFF=n ]
  199.       [ /Iinitfile | /-I ] [ /Linitfile ] [ /? ] [ /?&H ]
  200.  
  201. where:
  202.  
  203. "filespec" tells the routine which file or  files  are  to  be  processed.   The
  204. specification can include path and wildcards if desired.   Typically,  the  file
  205. names are *.HTM files.
  206.  
  207. "@listfile" allows you to have a variety of file specifications saved in a  text
  208. file named "listfile".  Each line  in  the  file  should  consist  of  one  file
  209. specification, each of which can include a path and wildcards if desired.  Blank
  210. lines and lines beginning with semi-colons, colons, or quotes are ignored.
  211.  
  212. "outfile" is the name of the output file to create.  Is overwritten if it exists
  213. already.  If no output file name is provided, the routine will  use  the  infile
  214. and provide  an  extension  of  *.OUT.   (The  default  .OUT  extension  can  be
  215. overridden using the /EXT=.xxx parameter.) An outfile  cannot  be  specified  if
  216. wildcards or @listfile are used for the input file specification.
  217.  
  218. "/EXT=.xxx" allows you to specify a different default  file  extension  for  the
  219. output file.  This parameter only matters if you do not  explicitly  specify  an
  220. output file name.  Initially defaults to "/EXT=.OUT".
  221.  
  222. "/WIDTH=n" specifies the desired line length for wrapping long  lines  and  also
  223. for centering.  Initially defaults to "/WIDTH=80".
  224.  
  225. "/SYMBOLS" says to allow (unless redefined  in  your  INI  file)  the  "(link)",
  226. "(image)", and "[Input]" indicators.  Initially defaults to "/-SYMBOLS".
  227.  
  228. "/-SYMBOLS" skips the indicators even if they're defined in your INI file.  This
  229. is initially the default.
  230.  
  231. "/ALL" says that if the program encounters what it thinks is just a  text  file,
  232. it should take the file and try to fix up CR/LF problems (Unix  files  end  with
  233. LF's instead of CR/LF which is what DOS needs)  and  that's  it.   This  can  be
  234. somewhat risky since it may misdiagnose a file but it should be safe  if  you're
  235. running it on your cache subdirectory.   Initially  defaults  to  "/-ALL"  which
  236. means it won't process it unless it thinks it's an HTML file.
  237.  
  238. "/SITE" shows the name of any <A HREF=...> location in  the  output  file.   For
  239. example, if a link goes to a specific Web page, the output file may include some
  240. reference like [http://www.thex-files.com/upepis.htm/].  Initially  defaults  to
  241. "/-SITE" (do not show the site name).
  242.  
  243. "/FSITE" is similar to /SITE except all of the references are shown as footnotes
  244. instead of being left in the text itself.  Initially defaults to "/-SITE".
  245.  
  246. "/-SITE" shows, at best, the symbolic reference if a link is provided on a page.
  247. Instead of some [http://...] thing, you'll see (link) provided that /SYMBOLS are
  248. turned on.  Initially defaults to "/-SITE".
  249.  
  250.  
  251. HTMSTRIP.DOC                         6                         Revised: 04/13/96
  252.  
  253. "/ALT" turns on the printing of the "Alt=" indicator in an  <IMG...>  statement.
  254. These are sometimes created by the page designer for use on buttons for  viewers
  255. who don't have graphical support.  Since text-only Web browsers are  dying  out,
  256. this is probably a standard which won't continue forever but it can't hurt.   If
  257. /ALT is specified, these alternate texts show up independently of  the  /SYMBOLS
  258. setting.  Initially defaults to "/-ALT".
  259.  
  260. "/-ALT" prevents the Alt= text in <IMG...> statements from showing up.  This  is
  261. initially the default.
  262.  
  263. "/SPACES"  turns  off  extra  vertical  spacing  between  sections.   There  are
  264. frequently lots of extra blank lines that appear in the output file  either  due
  265. to specific HTML requests or to insure proper reformatting.  Specifying  /SPACES
  266. allows these to stay there.
  267.  
  268. "/-SPACES" removes these extra blank lines.  This is initially the default.
  269.  
  270. "/WARNINGS" displays warnings when HTMSTRIP finds either  internal  problems  in
  271. the document or things it can't handle.  Initially defaults to "/-WARNINGS".
  272.  
  273. "/-WARNINGS" turns off the warning messages.  This is initially the default.
  274.  
  275. "/RULE=s" specifies that a string is to be repeated the width of the line.  This
  276. is used to separate sections.  The  string  can  be  a  single  character  (like
  277. "/RULE=-"), multiple characters (like "/RULE="- ""), it can contain decimal  and
  278. hexadecimal characters (like "/RULE=\066\097\116"--see BRUCEHEX.DOC), it can  be
  279. "/RULE=NULL" (which typically results in a blank line), or just  simply  "/RULE"
  280. (which is the same thing as "/RULE=-" if /BORDER=T and "RULE=\196" if  /BORDER=S
  281. or /BORDER=D).  Personally, if your printer supports IBM graphics characters,  I
  282. find "/RULE=\196" to be the most pleasing of the rule lines.
  283.  
  284. "/BORDER=c" specifies the type of border to use.  The possible choices  for  "c"
  285. are "D" (double), "S"  (single),  "T"  (text),  "B"  (blanks),  or  "N"  (none).
  286. /BORDER=B shows spaces instead of delimiters whereas /BORDER=N skips  the  blank
  287. lines between cells entirely..  Examples of the other three:
  288.  
  289.          <T>ext              <S>ingle             <D>ouble
  290.   +-----+-----+-----+  ┌─────┬─────┬─────┐  ╔═════╦═════╤═════╗
  291.   |  1  |  2  |  3  |  │     │     │     │  ║     ║     │     ║
  292.   +-----+-----+-----+  ├─────┼─────┼─────┤  ╠═════╬═════╪═════╣
  293.   |  4  |  5  |  6  |  │     │     │     │  ║     ║     │     ║
  294.   +-----+-----+-----+  ├─────┼─────┼─────┤  ╟─────╫─────┼─────╢
  295.   |  7  |  8  |  9  |  │     │     │     │  ║     ║     │     ║
  296.   +-----+-----+-----+  └─────┴─────┴─────┘  ╚═════╩═════╧═════╝
  297.  
  298. "/BUFF=n" specifies how many spaces to position on either side of  the  vertical
  299. bars in the tables.  Defaults to /BUFF=1.
  300.  
  301.  
  302. HTMSTRIP.DOC                         7                         Revised: 04/13/96
  303.  
  304. "/Iinitfile" says to read an initialization file with the file name  "initfile".
  305. The file specification *must* contain a period.  If no drive or path information
  306. is specified, the program will search for initfile  beginning  in  your  default
  307. subdirectory  and  then  going  throughout  your  DOS  path.   The  use  of   an
  308. initialization file is optional.  Initially defaults to "/IHTMSTRIP.INI".
  309.  
  310. "/-I" (or "/INULL") says to skip loading the initialization file.
  311.  
  312. "/Linitfile" says that the "&xxx;" and "<A>" etc lookup codes  are  found  in  a
  313. file other than from the default "/Iinitfile" file.  This is primarily useful if
  314. you want to have a master *.INI file and a separate code lookup table.
  315.  
  316. "/?" or "/HELP" or "HELP" shows you the syntax for the command.
  317.  
  318. "/?&H" gives you a hexadecimal and decimal conversion table.
  319.  
  320.  
  321. Author:
  322.  
  323. This program was written by Bruce Guthrie of Wayne Software.  It is free for use
  324. and redistribution provided relevant documentation is kept with the program,  no
  325. changes are made to the program or documentation, and it  is  not  bundled  with
  326. commercial programs or charged for separately.  People who need to bundle it  in
  327. for-sale packages must pay a $50 registration fee to  "Wayne  Software"  at  the
  328. following address.
  329.  
  330. Additional information about this and other Wayne Software programs can be found
  331. in the file BRUCEymm.DOC which should be included  in  the  original  ZIP  file.
  332. ("ymm" is replaced by the last digit of the year and the two digit month of  the
  333. release.  BRUCE508.DOC came out in August 1995.  This same naming convention  is
  334. used in naming the ZIP file that this program was  included  in.)  Comments  and
  335. suggestions can also be sent to:
  336.  
  337.                 Bruce Guthrie
  338.                 Wayne Software
  339.                 113 Sheffield St.
  340.                 Silver Spring, MD 20910
  341.  
  342.                 fax: (301) 588-8986
  343.                 e-mail: bguthrie@nmaa.org
  344.                 http://hjs.geol.uib.no/guthrie/
  345.  
  346. See BRUCEymm.DOC file for additional contact information.
  347.  
  348. Foreign users:  Please provide an Internet e-mail address in all correspondence.
  349.  
  350. 
  351.